什麼是 Block Theme？從 theme.json 說起

2026 iThome 鐵人賽

DAY 7

Vibe Coding

從一句話到一個網站：用 Vibe Coding 開發 WordPress Block Theme 的 30 天系列第 7 篇

18th鐵人賽 wordpress block theme theme.json

Oberon Lai

2026-08-10 10:27:35

201 瀏覽

分享至

上一篇解釋了範本階層在 Block Theme 幾乎原封不動，只是換了副檔名，這一篇要解釋一個更根本的問題：一個資料夾裡放的幾個 .html 檔 WordPress 憑什麼認得它是「Block Theme」而不是壞掉的傳統主題？答案就是theme.json，少了它，那些 templates/single.html 一個都不會生效。

在傳統佈景主題裡，決定主題「長相與行為」的責任散在好幾個地方：functions.php 註冊功能、style.css 定義樣式、還有一堆 add_theme_support() 呼叫，Block Theme 把這些整合到同一個檔案。理解 theme.json 最快的方式，就是把它想成「用宣告式設定，取代原本散落各處的 PHP 呼叫」。

先看它取代了什麼

傳統主題如果要開放編輯器的顏色選項、限制內容寬度、啟用特色圖片，你得在 functions.php 這樣寫：

add_theme_support( 'editor-color-palette', array(
	array( 'name' => '主色', 'slug' => 'primary', 'color' => '#0073aa' ),
) );
add_theme_support( 'post-thumbnails' );

同樣的事，在 Block Theme 裡改成一段 JSON：

{
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{ "name": "主色", "slug": "primary", "color": "#0073aa" }
			]
		},
		"layout": { "contentSize": "840px", "wideSize": "1100px" }
	}
}

差別不只是換個語法，add_theme_support() 是命令式的，你告訴 WordPress「去做這件事」。theme.json 是宣告式的，你描述「我要的結果長這樣」，剩下的交給 WordPress。

這個轉變帶來一個很實際的好處：同一份設定，前台輸出的 CSS、後台編輯器看到的選項、以及區塊工具列裡的控制項，全部在同一個檔案搞定，不會再出現「後台選得到、前台卻沒套上」的問題。

兩個主要區塊：settings 與 styles

theme.json 的內容九成落在兩個頂層鍵。

settings 決定「使用者能調什麼」。你在這裡開放的顏色、字級、間距，會變成編輯器裡實際可以點選的選項，像是上面的範例。沒開放的，編輯器就不會出現。這其實是一種設計約束，把品牌規範直接寫進工具，而不是寫在一份沒人看的 PDF 裡。

styles 決定「預設長什麼樣」。網站整體的背景色、內文字型、連結顏色、標題大小，都在這裡給預設值：

{
	"styles": {
		"color": { "background": "#ffffff", "text": "#1a1a1a" },
		"typography": { "fontSize": "18px", "lineHeight": "1.7" },
		"elements": {
			"link": { "color": { "text": "var(--wp--preset--color--primary)" } }
		}
	}
}

拿傳統主題類比：settings 像是你在 functions.php 裡註冊的那些「允許使用者調整的範圍」，styles 則像 style.css 裡寫死的預設樣式。以前這兩件事分別住在 PHP 和 CSS 兩個世界，現在併到同一份結構化設定裡。

為什麼這對 AI 開發特別友善

這點我在實際用 Claude Code 開發主題時感受最深。傳統主題的樣式邏輯藏在 CSS 選擇器的層層覆蓋、!important、還有跨檔案的繼承關係裡，AI 要改一個顏色，得先讀懂整條 cascade 才敢動手，改完還不確定會不會波及別處。

theme.json 是一份結構化、有 schema、單一來源的設定檔。要改主色，就是改 settings.color.palette 裡那一個值；要調內容寬度，就是改 layout.contentSize。

AI 不需要理解 CSS 的覆蓋順序，只要能讀懂 JSON，而讀 JSON 正是語言模型最擅長的事。第三部我們實際用 AI scaffold 主題時，你會看到 theme.json 幾乎是 AI 一次就能改對的檔案，這是宣告式設計帶來的好處。

一張表對照傳統主題

你想做的事	傳統佈景主題	Block Theme（theme.json）
定義配色	`add_theme_support('editor-color-palette')`	`settings.color.palette`
限制內容寬度	CSS `max-width` 硬寫	`settings.layout.contentSize`
設定預設字型	`style.css`	`styles.typography`
開放字級選項	自己寫 CSS class	`settings.typography.fontSizes`
連結顏色	CSS 選擇器	`styles.elements.link`
設定生效範圍	前台、後台各寫一次	一份設定同時套用兩端

Block Theme 全部集中在同一個檔案，這就是它最核心的設計哲學：把分散的樣式決策，整合成一份宣告式的單一來源。

一個常見的誤會

很多人第一次看到 theme.json 會以為那是不是所有 CSS 都得寫進 JSON？要澄清的是 theme.json 管的是設計系統層級的東西，色票、字級、間距、版面寬度這些「設計元素」（design token）。真正細節、一次性的樣式，你還是可以用傳統的 CSS 檔補上。theme.json 負責定調，CSS 負責收尾，兩者並存。

搞懂 theme.json，等於拿到了 Block Theme 的鑰匙，但光有鑰匙還不夠，明天我們要打開的是那扇更大的門：全站編輯（Full Site Editing），當使用者可以在後台直接拖拉整個網站的頁首、頁尾、模板，開發者和維運者的分工，會被徹底改寫。

文章目錄：https://oberonlai.blog/category/2026-ithome/

Hi, 我是 Oberon Lai，十多年前我從一個不懂程式的平面設計師，一頭栽進 WordPress 的世界。從佈景主題到外掛開發，從接案到自研產品，這段旅程讓我深刻理解：好的技術不只是寫出能跑的程式碼，而是真正解決人的問題。

我積極投入參與社群，公開演講紀錄如下：

我專精 WordPress 開發，從企業形象網站的設計與開發、佈景主題客製化，到既有網站的改版升級，提供完整的 WordPress 建置服務。開發面涵蓋外掛開發與維護、區塊編輯器（Gutenberg）客製區塊、ACF 與 Custom Post Type 的資料架構設計，以及 REST API 整合與 Multisite 多站架構建置。同時也協助網站效能改善與 SEO 調校、安全性檢測與強化，並導入自動化部署與版本控制流程，搭配長期的技術顧問與維運支援，讓網站上線後也能穩定運作。

亦提供 WooCommerce 商店的建置與設定，並串接綠界、LINE Pay、藍新等台灣主流金流。可依需求進行結帳頁面客製化、訂單狀態自動化流程設計，以及商品管理與庫存系統的客製開發；也支援 WooCommerce Subscription 定期定額、REST API 應用開發、報表與數據匯出等進階需求。此外，透過購物流程 UX 改善、電商網站效能調校與 HPOS 高效能訂單儲存相容開發，全面提升營運效率，並提供電商營運技術顧問服務。

AI 浪潮席捲而來，我選擇擁抱而非恐懼，我把 AI 融入開發工作流以及客戶的產品中，也持續累積「AI 看不見的部分」：真實踩坑經驗、最新漏洞情報那些只有第一線工程師才看得見的細節，如果你有任何 WordPress 的客製化需求或是 AI 開發相關的問題非常歡迎加入 LINE 官方帳號與我聯繫：

https://page.line.me/vrf7844t?oat_content=url&openQrModal=true

如果想要獲取 AI 開發實戰經驗也能訂閱我的電子報，每週五上午準時出刊：

https://oberonlai.blog/wordpress-newsletter/